﻿
Const DEFAULT_RESOURCE_GROUP_NAME:String		= "DEFAULT_RESOURCE_GROUP_NAME"
Const INTERNAL_RESOURCE_GROUP_NAME:String		= "INTERNAL_RESOURCE_GROUP_NAME"
Const AUTODETECT_RESOURCE_GROUP_NAME:String		= "AUTODETECT_RESOURCE_GROUP_NAME"

Type ResourceGroupManager
	
rem
bbdoc: Method to add a resource location to for a given resource group. 
about: Resource  locations are places which are searched to load resource files. When you choose to load a file, or to search for valid files to load, the resource locations are used. 
<p><b>Parameters:</b></p>
<table cellpadding="4" cellspacing="4" border="0">
<tr>
	<td><i>name</i></td><td>The name of the resource location; probably a directory, zip file, URL etc.</td>
</tr>
<tr>
	<td><i>locType</i></td>
	<td>
		The codename for the resource type, which must correspond to the Archive factory which is providing the implementation.
	</td>
</tr>
<tr>
	<td><i>resGroup</i></td>
	<td>
		The name of the resource group for which this location is to apply. ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME 
		is the default group which always exists, and can be used for resources which are unlikely to be unloaded until application 
		shutdown. Otherwise it must be the name of a group; if it has not already been created with createResourceGroup then it 
		is created automatically.
	</td>
</tr>
<tr>
	<td><i>recursive</i></td>
	<td>
		Whether subdirectories will be searched for files when using a pattern match (such as *.material), and whether 
		subdirectories will be indexed. This can slow down initial loading of the archive and searches. When opening a 
		resource you still need to use the fully qualified name, this allows duplicate names in alternate paths. 
	</td>
</tr>
</table>
endrem
	Method addResourceLocation(name:String, locType:String = "FileSystem", resGroup:String = DEFAULT_RESOURCE_GROUP_NAME, recursive:Byte = False)
		o_addResourceLocation(name.ToCString(), locType.ToCString(), resGroup.ToCString(), recursive);
	End Method
	
rem
bbdoc: Create a resource group. 
about: <p>A resource group allows you to define a set of resources that can be loaded / unloaded as a unit. For example, 
it might be all the resources used for the level of a game. There is always one predefined resource group called 
ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME, which is typically used to hold all resources which do not need to be 
unloaded until shutdown. There is another predefined resource group called ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME 
too, which should be used by OGRE internal only, the resources created in this group aren't supposed to modify, unload or 
remove by user. You can create additional ones so that you can control the life of your resources in whichever way you wish. 
There is one other predefined value, ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME; using this causes the group name 
to be derived at load time by searching for the resource in the resource locations of each group in turn.</p>

<p>Once you have defined a resource group, resources which will be loaded as part of it are defined in one of 3 ways:
<ol>
<li> Manually through declareResource(); this is useful for scripted declarations since it is entirely generalised, 
and does not create Resource instances right away</li>
<li> Through the use of scripts; some ResourceManager subtypes have script formats (e.g. .material, .overlay) which 
can be used to declare resources</li>
<li> By calling ResourceManager::create to create a resource manually. This resource will go on the list for it's 
group and will be loaded and unloaded with that group</li>
</ol>
You must remember to call initialiseResourceGroup if you intend to use the first 2 types. </p>
<p><b>Parameters:</b></p>
<table cellpadding="4" cellspacing="4" border="0">
<tr>
	<td><i>name</i></td><td>The name to give the resource group.</td>
</tr>
<tr>
	<td><i>inGlobalPool</i></td>
	<td>if true the resource will be loaded even a different group was requested in the load method as a parameter.</td>
</tr>
</table>
endrem
	Method createResourceGroup(name:String, inGlobalPool:Byte = True)
		o_createResourceGroup(name.ToCString(), inGlobalPool)
	End Method
	
rem
bbdoc:
about: After creating a resource group, adding some resource locations, and perhaps pre-declaring some resources using 
declareResource(), but before you need to use the resources in the group, you should call this method to initialise the 
group. By calling this, you are triggering the following processes:
<ol>
<li>Scripts for all resource types which support scripting are parsed from the resource locations, and resources within 
them are created (but not loaded yet).</li>
<li>Creates all the resources which have just pre-declared using declareResource (again, these are not loaded yet)</li>
</ol>
<p>So what this essentially does is create a bunch of unloaded Resource entries in the respective ResourceManagers based 
on scripts, and resources you've pre-declared. That means that code looking for these resources will find them, but they 
won't be taking up much memory yet, until they are either used, or they are loaded in bulk using loadResourceGroup. Loading 
the resource group in bulk is entirely optional, but has the advantage of coming with progress reporting as resources are loaded.</p>
<p>Failure to call this method means that loadResourceGroup will do nothing, and any resources you define in scripts will 
not be found. Similarly, once you have called this method you won't be able to pick up any new scripts or pre-declared resources, 
unless you call clearResourceGroup, set up declared resources, and call this method again.</p>
<p><b>Note:</b> When you call Root::initialise, all resource groups that have already been created are automatically 
initialised too. Therefore you do not need to call this method for groups you define and set up before you call Root::initialise. 
However, since one of the most useful features of resource groups is to set them up after the main system initialisation 
has occurred (e.g. a group per game level), you must remember to call this method for the groups you create after this.</p>
<p><b>Parameters:</b></p>
<table cellpadding="4" cellspacing="4" border="0">
<tr>
	<td><i>name</i></td><td>The name of the resource group to initialise</td>
</tr>
</table>
endrem
	Method initialiseResourceGroup(resourceGroup:String = DEFAULT_RESOURCE_GROUP_NAME)
		o_initialiseResourceGroup(resourceGroup)
	End Method
End Type